// ==================================================================================
// Shared Genomics Project MPI Codebase
// Version 1.0 30/04/2010
//
// (c) 2010 University of Manchester all rights reserved
//
// This file is distributed under the GNU General Public License, Version 2.  
// Please see the file COPYING.txt for more details
// ==================================================================================

#ifndef _SOLFILE_H_
#define _SOLFILE_H_

#include "options.h"
#include "sample.h"

#ifdef __cplusplus
extern "C" {
#endif

/*!
\file
\brief		Strata or Layer (SOL) Utility Functions
\ingroup	gio
\details
	Header file to create a strata or layer (SOL) file to group people in a genomic data-set into specific layers.<br>
	The source of membership data is a PLINK compatible phenotype (PHE) file.<br>
	This headers file also provides methods to create set-based permutation indices for randomised calculations
	on a genomic data-set.<br>
	Typically a SOL file uses the suffix \ref SUFFIX_SOL_FILE.
*/

/*! \brief Maximum string width for a level value. */
#define MAX_LEVEL_WIDTH 80

/*! \brief Maximum No. levels. */
#define MAX_LEVELS 100

/*!
\brief Parse a string array to get unique levels.
\details
	Function parses a string array in order to get a unique list of levels.<br>
	%Set the allowEmptyStrings flag to TRUE if an empty string is a level.<br>
	If a column contains a continuous variable whose number of unique values are
	greater than the size of the destination array, this function flags an error.<br>
	Individuals may have been removed from a data-set by a filtering operation; these
	people are flagged in  the 'items_to_ignore' array.<br>
	A string value set as \ref MISSING_LEVEL is ignored.<br>
	The list of 'found' levels is sorted alphabetically.
\param [in] src Source array of level data
\param [in] nSrc Size of the source array
\param [in,out] dst Destination array, the unique list of levels
\param [in] nDst Size of the destination array
\param [in,out] nLevels Pointer storing No. levels written to the destination array
\param [in] allowEmptyStrings Flag if empty string to be classed as a level
\param [in] items_to_ignore elements to ignore in the source array
\returns 1 on success or 0 on failure
*/
int _get_levels(char **src, int nSrc, char **dst, int nDst, int *nLevels, BOOL allowEmptyStrings, BOOL *items_to_ignore);

/*! 
\brief Parse a phenotype file to create a SOL file and SOL permutation file 
\details
	The filepath to a input PHE file is bound to \ref selected_options::szPheFileName.<br>
	The output SOL file containing the strata membership data for each person in 
	a data-set is a concatonation of \ref selected_options::rdir,
	\ref selected_options::szRunId and \ref SUFFIX_SOL_FILE.<br>
	The output PERM file containing the strata permutation data 
	is a concatonation of of \ref selected_options::rdir,
	\ref selected_options::szRunId and \ref SUFFIX_PERM_FILE.<br>
	%Set skip_missing = FALSE for the SOL file to be compatible with PLINK
\param [in] ops Input/Output filepaths
\param [in] skip_missing If FALSE then missing phenotypes not written to the SOL file.
\returns 1 on success or 0 on failure
*/
int solfile_create(struct selected_options *ops, BOOL skip_missing);

/*! 
\brief Load a SOL file and bind data to existing sample array.
\details
	The SOL file is read and the \ref sample::sol assigned an appropriate 
	numerical value denoting set membership.<br>
	Data from the SOL file and sample array are combined by array index.<br>
	Make sure that solfile_create() is called with skip_missing = FALSE otherwise
	the data mapping will fail.<br>
	The input file path is bound to selected_options::szSolFileName.
\param [in] ops Input location
\param [in,out] samples The sample array
\param [in] nSamples Size of the sample array
\returns 1 on success or 0 on failure
*/
int solfile_load(struct selected_options *ops, struct sample *samples, int nSamples);

#ifdef __cplusplus
}
#endif

#endif // _SOLFILE_H_
